Skip to content

docs: align README with tested product reality - #38

Merged
jusso-dev merged 7 commits into
mainfrom
agent/issue18
Jul 27, 2026
Merged

docs: align README with tested product reality#38
jusso-dev merged 7 commits into
mainfrom
agent/issue18

Conversation

@jusso-dev

@jusso-dev jusso-dev commented Jul 27, 2026 •
edited by coderabbitai Bot
Loading

Copy link
Copy Markdown
Owner

Summary

  • rewrites the README around currently implemented routes, task-board behaviour, starter Alfie/Jessie/Parker missions, and explicit product ownership boundaries
  • separates clean-install behaviour from synthetic demo and screenshot data
  • documents the exact Kelpie/Tawny/Bower mock-versus-configured status without claiming live-product certification or Slack support
  • adds verified homelab, trusted-origin, generated-credential, private Codex-volume, backup, restore, security, troubleshooting, browser, and architecture guidance
  • supports and persists a reviewed MUSTER_IMAGE OCI digest while retaining MUSTER_VERSION compatibility
  • pins the documented public amd64 image to the reviewed a37ea88 manifest digest

Verification

  • pnpm check (passed; local Node 22 emitted the expected engine warning because the repository declares Node 24+)
  • pnpm exec prettier --check README.md docs/operations/deployment.md
  • bash -n scripts/install-homelab.sh
  • homelab Compose configuration rendered through remote Docker context m3-max, including the documented digest and setup profile
  • GHCR manifest verified as public linux/amd64 with SBOM/provenance attestation manifest
  • README local-link check and HTTP checks for Kelpie, Tawny, Bower, and issue P1: Make Slack first-class for portable governed agent harnesses #33
  • focused credential/secret-pattern scan and git diff --check

Closes #18

Summary by CodeRabbit

  • New Features

    • Homelab deployments can now select a specific Muster version or container image through environment settings.
    • Docker Compose supports overriding the default Muster image reference.

  • Documentation

    • Reorganized and expanded the README with updated setup, operations, security, troubleshooting, testing, licensing, and connector guidance.
    • Clarified Codex authentication and credential storage for root and homelab deployments.
    • Added guidance for task board missions, demo data separation, image installation, and current application capabilities.

@coderabbitai

coderabbitai Bot commented Jul 27, 2026 •
edited
Loading

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@jusso-dev, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 10 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8e91c108-714c-4d3e-9982-d707d857f1c3

📥 Commits

Reviewing files that changed from the base of the PR and between e29c027 and 935feac.

📒 Files selected for processing (7)
  • .github/workflows/ci.yml
  • README.md
  • deploy/docker/.env.homelab.example
  • deploy/docker/README.md
  • package.json
  • scripts/install-homelab.sh
  • scripts/test-install-homelab.sh
📝 Walkthrough

Walkthrough

The README was rewritten around the governed-workspace model and verified product behavior. Homelab installation now supports explicit image and version overrides, Docker Compose resolves the selected image, and deployment documentation clarifies Codex credential volume names.

Changes

Product documentation and homelab deployment

Layer / File(s) Summary
Product and operational documentation
README.md		 Documents the governed-workspace model, verified features, installation modes, connector status, security and operations, troubleshooting, roadmap, testing, and Apache-2.0 licensing.
Homelab image override flow
scripts/install-homelab.sh, deploy/docker/docker-compose.homelab.yml, docs/operations/deployment.md		 Persists explicit MUSTER_VERSION or MUSTER_IMAGE values before deployment, uses the configured image in Docker Compose, and distinguishes root and homelab Codex credential volumes.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant install-homelab.sh
  participant .env.homelab
  participant Docker Compose
  participant Muster image
  install-homelab.sh->>.env.homelab: Write MUSTER_VERSION or MUSTER_IMAGE
  Docker Compose->>.env.homelab: Resolve image reference
  Docker Compose->>Muster image: Pull and start selected image
Loading
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly describes the README alignment with tested product reality and matches the main documentation-focused change.
Linked Issues check ✅ Passed The README rewrite and homelab/deployment updates address the requested verified-product messaging, mock status, clean install, and image pinning.
Out of Scope Changes check ✅ Passed The changes stay focused on README/docs plus supporting homelab install and compose updates needed for the documented workflow.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch agent/issue18

Comment @coderabbitai help to get the list of available commands.

@jusso-dev

jusso-dev commented Jul 27, 2026

Copy link
Copy Markdown
Owner Author

Independent review fixes landed in 180427c:

  • Fresh install now creates the required Tawny and Kelpie external networks when absent.
  • MUSTER_IMAGE and MUSTER_VERSION are mutually exclusive, validated, and transition without leaving a stale higher-precedence value.
  • The installer no longer sources dotenv as shell code.
  • A synthetic installer regression test covers fresh digest install plus digest/tag transitions and network creation.
  • The documented browser-test setup now starts MinIO and bucket initialisation.
  • Tracked homelab defaults use muster.example.lan; the private LAN address was removed from public docs/config.

Focused checks passed: installer regression, Bash syntax, Prettier, diff check, private-address scan, and remote Compose digest rendering.

@jusso-dev

jusso-dev commented Jul 27, 2026

Copy link
Copy Markdown
Owner Author

Final review fixes landed in 935feac: fresh installs now require an immutable digest/SHA reference; persisted mutable/conflicting references fail closed; deployment docs use the current reviewed digest; and CI runs the installer regression covering missing input, mutable persisted tags, network creation, and digest/tag transitions.

@jusso-dev
jusso-dev merged commit 52c8a64 into main Jul 27, 2026
7 checks passed
@jusso-dev
jusso-dev deleted the agent/issue18 branch July 27, 2026 03:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

P1: Rewrite README to match tested product reality

1 participant

@jusso-dev